home *** CD-ROM | disk | FTP | other *** search
/ The 640 MEG Shareware Studio 2 / The 640 Meg Shareware Studio CD-ROM Volume II (Data Express)(1993).ISO / clang / 16550.zip / FACT.DOC < prev    next >
Text File  |  1991-07-20  |  12KB  |  262 lines
  1.    FIFO Asynchronous Communication Test Software for NS16550/16552 UARTs
  2.    =====================================================================
  3.         
  4.             National Semiconductor Corporation
  5.             Greg DeJager      February 8, 1989
  6.  
  7.             Adapted from LBT.C -- Loopback Test Rev 1.1 
  8.             Developed by:  Brian A. Berg
  9.                            BERG SOFTWARE DESIGN
  10.  
  11.  
  12. Summary of Files
  13. --------------------------
  14.  
  15. FACT.C        C source code: main program, subroutines and interrupt handler
  16. SERIO.H        header file containing UART definitions for C code use
  17. STDHDR.H    header file containing "standard" definitions for C code use
  18. FACT.EXE    executable FACT program; only this file is needed to run the FACT
  19.  
  20.  
  21.              Intro, Hardware Setup and Program Operation
  22.         ===========================================
  23.  
  24. This test was developed to run on all IBM AT or AT compatible architectures
  25. as well as IBM PS/2 Model 30 - 80 machines.  System requirements include
  26. two separate machines with an NS16550 or NS16552 UART located at COM1, 2 or 3
  27. and an RS-232 DTE to DTE interface between them.  The DTE-DTE interface must 
  28. have the following connections:
  29.         Tx----------------------------Rx
  30.         Rx----------------------------Tx
  31.         RTS--------------------------CTS
  32.         CTS--------------------------RTS
  33.         GND--------------------------GND
  34.  
  35. The executable software is titled FACT.EXE.  To run the test, the above 
  36. hardware must be set up and after entering the proper directory, the user
  37. must type FACT <enter> on both machines.  The program will prompt the user
  38. to start both machines and then hit a key to begin the test.  This procedure 
  39. is necessary to ensure that all modem control outputs are deasserted before 
  40. program start-up so that a machine won't begin transmitting before the 
  41. other is ready to receive.  Full duplex transmission begins after a key is
  42. hit on both machines and each machine has exchanged initial RTS signals.
  43. Proper test operation is indicated by a '$' and '*' character being printed
  44. to the screen every 2560 characters received.
  45.  
  46. All operations are interrupt driven.  UART line status, receiver and transmitter
  47. interrupts are enabled.  When not servicing interrupts, the CPU sits in a
  48. loop checking for a keyboard hit (means for user to stop test) and for errors
  49. produced within the interrupt service routines.  A transmitter interrupt is
  50. generated whenever the transmitter FIFO empties.  The CPU services the interrupt
  51. by filling the FIFO with the next 16 characters to be transmitted.  Transmit
  52. data is written to the FIFO only as long as CTS remains asserted.  A receiver 
  53. interrupt is generated when 14 characters have entered the receiver FIFO.  
  54. The CPU immediately deasserts RTS to stop any further transmission from the 
  55. other machine.  It then reads bytes out of the FIFO, comparing each of them to
  56. an expected value.  Data transmitted and received sequences between 00 and FFH.
  57. If a mismatch occurs, the expected and received data are displayed and the 
  58. program stops.  A line status interrupt results from an Overrun, Framing or 
  59. Parity error and Break condition.  Upon receiving the status interrupt, the 
  60. program prints the corrupted data and the line status register value and exits 
  61. the program.  Inconsistencies between the Interrupt ID and Line Status Registers
  62. also cause error messages to be printed and the program to stop.
  63.  
  64. There is a restriction associated with porgram operation.  The maximum baudrate
  65. that can be selected is 56k; however, this baudrate is limited by the processor
  66. speed and the host system.  A 10Mhz AT compatible and 12Mhz PS/2 Model 30
  67. operate reliably at a maximum of 19.2k baud.  At higher baud rates operation
  68. is system dependent due to the overhead involved with processing the interrupts.
  69.  
  70. The default com port is COM1 and default baudrate is 9600.  However, the user 
  71. can control these options by specifying arguments on the command line.  Arguments
  72. must be separated by spaces.  The first argument is a selection of COM1, COM2
  73. or COM3 (eg.  FACT 2  selects COM2).  The second argument is a decimal 
  74. divisor from 2 through 2304 which specifies a baudrate from 56k to 50 (the
  75. default is 12, 9600 baud).  The baudrate arguement must be proceeded on the
  76. command line by the COM port designation.  Again, specifying no arguments
  77. causes a default of COM1, 9600 baud to be used.  A command line which causes
  78. the program to use COM3 and 19.2k baud is: FACT 3 6.  A help screen is printed
  79. if any improper argument is used or if FACT H is entered. 
  80.  
  81.  
  82.                Programmer's Guide for FACT.C -- Rev 1.0
  83.  
  84. Help Screen for FACT
  85. -------------------
  86.  
  87. NOTE: The following is displayed if any incorrect arguments are supplied
  88.     to the FACT (this includes entering "fact help")
  89.  
  90.  
  91. HELP Screen for NS16550/NS16552 FIFO Asynchronous Communications Test (FACT)
  92.  
  93. USAGE: fact [<COM-number> [<baudrate-divisor>]]
  94.                 arg1              arg2           
  95.  ('fact' may be followed by no args, arg1 or arg1+2)
  96.  
  97.   ARGUMENT     MINIMUM VALUE    MAXIMUM VALUE    DEFAULT VALUE 
  98. ============  ===============  ===============   ==============
  99.  COM-number    1 (for COM1)     3 (for COM3)           1  
  100.               (serial line 0)  (serial line 2)       (COM1)
  101.  
  102.   baudrate-   2 (56000 baud)   2304 (50 baud)         12        
  103.    divisor     (based on 1.8432 MHz crystal)      (9600 baud)   
  104.     *  Sample baudrate divisors: for baud= 1200, use 96  *     
  105.     *                                      2400      48  *     
  106.     *                                      4800      24  *     
  107.     *                                      9600      12  *     
  108.     *                                     19200       6  *     
  109.  
  110.                             Page 2 of 4
  111.  
  112.  
  113.                   Programmer's Guide for FACT   
  114.                   ===========================
  115.  
  116.  
  117. Summary of FACT.C Subroutines
  118. -----------------------------
  119.  
  120. NOTE: As the code itself is heavily commented, it should be inspected if
  121.     further clarification is necessary.
  122.  
  123. The following subroutines are contained in this file:
  124.  
  125. void main(int, char **);        /* main program */
  126. void interrupt far serint(void);    /* serial interrupt handler */
  127. void procarg(int, char **);        /* process invocation arguments */
  128. void savepar(void);            /* save our environment parameters */
  129. void rstrpar(void);            /* restore our environment parameters */
  130. void dspstr(UCHAR *);            /* display a string on the console */
  131. void usage(void);            /* display usage info and exit */
  132.  
  133.  
  134. 1. main(): main program
  135.  
  136. The main program initializes the system as follows:
  137.   processes invocation arguments by calling procarg(),
  138.   uses the CLEAR_REGS() macro to clear the RBR, LSR, IIR, MCR and FCR registers,  
  139.   saves environment parameters by calling savepar(),
  140.   sets the requested (or default) baud rate and LCR register,
  141.   prints name of test to screen
  142.   prints "Hit a key when other program has been started" and waits for keyboard hit,
  143.   clears FIFOs, sets receiver trigger level and verifies existence of FIFOs,
  144.   enables IRQ by setting OUT2,
  145.   enables UART receiver and line status interrupts,
  146.   asserts RTS and after receiving CTS (RTS from other machine),
  147.   it prompts the operator to "Hit any non-control key to stop" the program.
  148.  
  149. It then starts full duplex communication by enabling transmitter interrupts
  150.   and then loops until either the global variable "errflag" changes from
  151.   FALSE (0) to TRUE (a specific error code), or the operator strikes any
  152.   non-control keyboard key.  The errflag variable is set by the interrupt 
  153.   handler as described for serint().
  154. While this loop is active, the global variable "tick" is inspected.  If it is
  155.   non-zero, either "$" or "*" is displayed at one place on the screen in order
  156.   to inform the operator that the program is active.  This is facilitated by
  157.   use of a flip-flop variable to index one of two ASCII strings.  The character
  158.   is changed every 2560 bytes received.
  159. After exiting this loop, the program waits for the TEMT bit in the LSR to be
  160.   set to indicate an empty transmitter FIFO.  The CLEAR_REGS() macro is again
  161.   invoked.  An 'End of program' message is printed and, if the interrupt
  162.   handler found an error, an error message corresponding to the code in the 
  163.   variable errflag is output.
  164.  
  165.                             Page 3 of 4
  166.  
  167.  
  168.                         Programmer's Guide for the FACT
  169.                      ===============================
  170.  
  171.  
  172. Summary of FACT.C Subroutines (continued)
  173. ----------------------------------------
  174.  
  175. 2. serint(): serial port interrupt handler
  176.  
  177. The interrupt handler first checks if the global "errflag" is TRUE.  If so,
  178.   the interrupt is ignored by disabling UART interrupts and by sending the
  179.   PIC an EOI and exiting.
  180. Then the IIR is read and each interrupt type is handled:
  181.     NO Interrupt Pending:
  182.         errflag <- False Interrupt error message code
  183.  
  184.     Receiver Line STatus interrupt:
  185.         read and store LSR 
  186.         read and store RBR 
  187.         errflag <- Status error message code
  188.  
  189.     Received Data AVailable (RDAV):
  190.         clear RTS 
  191.         while bytes still in Receiver FIFO and no mismatches found:
  192.           read a byte and compare to expected value
  193.           if mismatch is found, errflag <- Mismatch Error code
  194.           else increment byte counter variable and set 'tick if
  195.             2560 characters were received
  196.         after receiver FIFO is emptied,if no errors were found, 
  197.           RTS is reasserted
  198.     Transmitter Holding Register Empty:
  199.         the LSR is read
  200.         verify THRE bit set, errflag <- Tx Error message code if not
  201.         while CTS is asserted and transmitter FIFO not full (16 bytes):
  202.           write next byte to transmitter FIFO
  203.     Receiver FIFO Character Timeout:
  204.         errflag <- Timeout error code
  205.         if Data Ready bit not set, errflag <- Timeout error code
  206.         else while bytes still in Receiver FIFO:
  207.           read a byte and compare to expected value
  208.           if mismatch found, errflag <- Mismatch Error code
  209.   
  210.     any other value for the IIR:
  211.         errflag <- IIR Error code
  212.  
  213. All UART interrupts are disabled (IER <- 0)
  214. If no errors were found, all interrupts are reenabled.  This creates an edge
  215.   on the INTR line if multiple interrupts are pending.
  216.      
  217. An EOI is sent to the PIC.
  218. (NOTE: an IRET instruction is automatically generated to exit this int. handler)
  219.  
  220.                             Page 4 of 4
  221.  
  222.  
  223.                     Programmer's Guide for FACT 
  224.                     ===========================
  225.  
  226. Summary of FACT.C Subroutines (concluded)
  227. ----------------------------------------
  228.  
  229. 3. procarg(): process invocation arguments
  230.  
  231.     The invocation arguments as defined in the help screen are validated
  232.       by this routine.  The help screen itself is displayed by calling
  233.       usage() if any illegal arguments are found.
  234.     Based on the COM argument (or its default), the interrupt vector number
  235.       and UART base address are set up for global use.  The existence of
  236.       the requested COM port is verified; its non-existence causes program
  237.       termination.
  238.  
  239.  
  240. 4. savepar(): save our environment parameters
  241.  
  242.     This routine saves the original interrupt vector, ctrl-break/ctrl-c
  243.       status and PIC mask, and then sets these up as required for FACT use.
  244.       It also saves some of the UART register values.
  245.  
  246.  
  247. 5. rstrpar(): restore our environment parameters
  248.  
  249.     This routine is the complement for savepar(): it restores the saved
  250.       registers, interrupt vector, ctrl-break/ctrl-c status and PIC mask.
  251.  
  252.  
  253. 6. dspstr(): display a string of characters on the console
  254.  
  255.     This routine uses the INT 10H software interrupt to display a string a
  256.       character at a time.
  257.  
  258.  
  259. 7. usage(): display program usage information and terminate (never return)
  260.  
  261.     This routine displays the help screen and terminates the program.
  262.